---
title: Style Guide
slug: /style-guide
description: All contributions to the Sui documentation must adhere to the style guide.
keywords: [ style guide, documentation style, accessibility of docs, formatting of docs, capitalization, grammar, tense, headings, lists, tables, word choice ]
---

This document defines the styles, vocabulary usage, and content formatting for Sui documentation. Entries are in alphabetical order. A style guide is never finished; expect continued iterations to add additional styles, additional information to existing styles, and infrequently a change to an existing style.

## Editorial considerations {#editorial-considerations}

- **Use simple words and concise sentences.**  
  Prefer plain, direct language over complex or academic phrasing. Short sentences improve readability and are easier to localize.  

- **Avoid redefining common words.**  
  Do not give familiar words new or unexpected meanings (for example, do not use "object" to mean something other than its standard technical or everyday sense). This prevents confusion, especially for new readers.  

- **Use technical terms with care.**  
  Introduce technical terms only when necessary. Define them clearly the first time, and use them consistently throughout the documentation.  

- **Avoid jargon and slang.**  
  Do not assume readers understand informal expressions, company-specific shorthand, or unnecessary buzzwords. Use precise terms instead.  

- **Prefer active, descriptive phrasing.**  
  Instead of vague phrases like, "do the thing," explain the action explicitly: "Deploy the contract" or "Restart the node."  

- **Write for a global audience.**  
  Keep in mind that many readers are non-native English speakers. Favor clarity over cleverness, and avoid idioms or culturally specific references.  

---

## Spelling and grammar 

#### Spelling {#spelling}

Use US English spelling in source content.

#### Avoid Latin abbreviations {#latin-abbreviations}

Because many languages are not Latin-based, avoid using Latin abbreviations (e.g., i.e., etc., et. al, and so on). Prefer ex. or complete phrases like "for example", "and so on", and similar.

#### Grammar {#grammar}

##### Active voice {#active-voice}

Use active voice whenever possible. Active voice is direct, clear, and uses fewer words. Passive voice is often less clear, awkward, and uses more words.

> ✅ **Active:** She installed the software.

> ❌ **Passive:** The software was installed by her.

##### Person {#person}

- First person → I or we 

- Second person → you 

- Third person → he, she, they, it, product names

Use **second person** ("you"). **Do not** use first or third person ("I" or "we").

> ✅ You can view the transaction history in the Sui Explorer.

> ❌ We can view the transaction history in the Sui Explorer.

##### Present tense {#present-tense}

Use present tense whenever possible. Reserve future tense only for events that will happen at a specific future time, such as a scheduled product release.

Do not use future tense when describing product behavior or writing task instructions. From the reader's perspective, actions occur in the present as they follow the steps.  

> **Example: Present tense**
>
> Click **Save** to save the updated file.  
> When you click **Save**, your device writes the changes to disk.  
> To save a file after you modify it, click **Save**.  

> **Example: Future tense (avoid)**
>
> Your changes will be saved when you click **Save**.  
> When you click **Save**, the file will be written to disk.  

Although technically correct, the future tense creates distance between the user and the action. It also makes the text harder to understand for ESL readers and more difficult to localize. In reality, the action happens immediately when the user clicks **Save**.

##### Punctuation

1. Sentences

    - Use a period at the end of a complete sentence. 

    - Use a single space after a period (never two).  

2. Lists

    - Full sentences in lists: End each item with a period.  

    - Fragments or single words in lists: Do not use periods.  

    - Mixed lists: Avoid mixing fragments and full sentences. Rewrite for consistency.  

3. Parentheses

    - If the entire sentence is inside parentheses, place the period inside.  

    - If the parentheses are part of a sentence, place the period outside.  

    - Never place a period before the closing parenthesis.  

4. Abbreviations

    - Keep the period as part of an abbreviation. However, [do not use Latin abbreviations](#latin-abbreviations). 

5. Headings and titles

    - Do not use periods after headings, subheadings, or titles (unless the title ends in an abbreviation).  

6. Numbers and decimals

    - Do not add an extra period after a decimal number.  

##### Parentheses 

Use parentheses to add clarifying or supplemental information that is not essential to the main sentence.

Avoid overusing parentheses. If the information is important, integrate it into the sentence instead of isolating it.

#### Avoid using (s) for plurals

Use “(s)” only if required for legal, contractual, or regulatory text where precision demands explicit acknowledgment of both singular and plural forms. Otherwise, use the plural form without parentheses. 

##### Oxford (serial) commas {#oxford-serial-commas}

Do use serial commas.

> ✅ You must install Cargo, Rust, Docker, and the Sui CLI to create a Sui node.

> ❌ You must install Cargo, Rust, Docker and the Sui CLI to create a Sui node.

##### Numbers {#numbers}

Do not write out numbers when referring to a number of items; always use the numerical value. 

> The folder contains 24 files.
> One folder contains 7 files, and the other contains 24 files.
> At least 20 pieces of candy fell off the table.

Do write out numbers when they are grammatically part of the sentence.

> One can always include extra documentation to support the theory.
> The client checks if the checkpoint is the last one of the epoch.

##### Quotation marks 

Do not use quotation marks, except for the single exception "Hello, World!".

##### Ampersands

Do not use ampersands (`&`) in content to replace `and` as the word is more accessible and less error-prone for some programmatic use cases. If you absolutely must include an ampersand in content, escape it using `&amp;`.

##### Exclamations

Do not use exclamation marks. If you'd like to express excitement, such as:

> Congratulations! You've finished the tutorial.

Use the confetti emoji instead:

> Congratulations, you've finished the tutorial. 🎉 

--- 

## Terminology and vocabulary

For consistency, the Sui documentation must use the following terms and phrases with the indicated capitalization (unless sentence structure determines otherwise). This list is not exhaustive and will be updated over time. 

|     **Category**       |             **Words and terms**               |    **Notes**   |
| ---------------------- |---------------------------------------------- | -------------- |
| **Always capitalized** | [Proper nouns](#proper-nouns), [product names](#product-names), names of example dApps (Coin Flip, Blackjack, etc), Archival Store and Service, Archival Store, Archival Service, Coin Registry, Currency Standard, DeepBook Indexer, DeepBookV3, Devnet, GraphQL RPC, General-purpose Indexer, ID, Localnet, Kiosk (when referring to the standard), Mainnet, Mysticeti, One-Time Witness, Operation Cap, Sui, Sui CLI, Sui Client PTB CLI, Sui Closed-Loop Token / Closed-Loop Token, Sui dApp Kit, Sui Explorer, SuiJSON, Sui Keystore, Sui Keytool, SuiLink, Sui Object Display, SuiPlay0X1, SUI, SUI token, Testnet, Wallet Standard, Web2, Web3, zkSend SDK | Use capitalization consistently for branding and product-specific references |
| **Always lowercase**   | casual history, casual order, certificate, dApp, epoch, equivocation, eventual consistency, finality, gas, genesis, kiosk (when referring to an instance), object, oracle, recovery passphrase (mnemonic), smart contract, soulbound, Sui framework, Sui object, total order, transaction, transfer, validator, wallet | Use lowercase when referring to general concepts rather than branded terms   |
| **Never hyphenated**   | key pair, layer 1, open source, use case                  | Keep these words separate, no hyphen                                         |
| **Always hyphenated**  | burn-only (currency supplies), depth-first search, multi-writer objects, off-chain, off-device, on-chain, on-device, One-Time Witness, peer-to-peer, proof-of-stake, single-writer objects  | Maintain hyphen for clarity and correctness  |
| **Word preference**    | Use "might" in place of "may"                 | The word may has a secondary definition that implies permission rather than possibility. |
| **Word preference**    | Do not start sentences with "Please note" or "Note"              | It can be argued that any sentence could be prefaced with these words. |
| **Word preference**    | Use "through" in place of "via"                 | Indicates a more direct action. | 
| **Word preference**    | Use "because" in place of "since"                 | More direct. | 
| **Word preference**   | Use "basic" in place of "simple"    | Frustrating for user if something is not simple but is described as such. |



### Nodes

When referencing nodes (full, archival, validator, and so on), use:

- Lowercase _full node_ when referring to the conceptual role in the network.
    “Every RPC provider must enable gRPC on their full node.”
- Capitalize _Sui Full Node_ when referring to the official software binary/package that Sui distributes.
    “Download and run the Sui Full Node from GitHub to connect to Mainnet.”

### Proper nouns {#proper-nouns}

Capitalize proper nouns throughout.

Proper nouns include:

- Names of people: Bob Ross

- Named places: San Francisco, Union Station

- Products and services: Slack, Google Play

- Trademarks: Coca-Cola

- Book titles: The Move Book

- Standards or technologies: Local Area Network (LAN)

### Product names {#product-names}

Product names are proper nouns. Capitalize all words of a product name. When referring to a product, use only the product name without "the". When referring specifically to a Sui wallet, use Sui Wallet or Ethos Wallet and not just wallet. Users likely have multiple wallets, and we want to make it clear which wallet. Use wallet generically when referring to the concept of a wallet.

> There are several types of wallets to choose from.

> Never share the recovery passphrase for your wallet with anyone.

> The Sui network supports the following wallets:
> - Sui Wallet
> - Ethos Wallet
> - Coinbase Wallet

### Acronyms and abbreviations

#### Acronyms {#acronyms}

Spell out a term or phrase on first use in a topic, followed by the acronym in parentheses. Then use the acronym for subsequent mentions.

> Example: You can mint non-fungible tokens (NFTs) using your Sui Wallet. To view an NFT after you mint it, click the NFTs tab of your wallet.

##### Terms that should always be used as acronyms 

- CLI  
- SDK

#### Abbreviations 

Abbreviations for words should not be used. Write out the full word for clarity.

> ✅ Open the tab for more information.

> ❌ Open the tab for more info.

--- 

## Capitalization {#capitalization}

#### Title capitalization {#title-capitalization}

For title capitalization, follow these guidelines:

- Do not capitalize short conjunctions and prepositions (a, an, and, but, for, in, or, so, to, with, yet), unless they are the first or last word.

- Capitalize all other words (including 'Is' and 'Be' as they are verbs).

- Capitalize the word after a hyphen.

- Match casing for commands or special terms, such as cURL or dApp.

- Match the casing for API elements and programming language keywords.

#### Section heading capitalization 

Use sentence capitalization for section headings, table cells or headers, list items, captions, alt text, and error messages.

#### Body text capitalization 

##### Do:

Always capitalize the first word of a new sentence.

Always capitalize proper nouns and product names. See [words to always capitalize](#word-list) for the exhaustive list of capitalized terms. 

##### Do not:

Do not use all uppercase for emphasis; use bold instead.

> Example: IMPORTANT vs **Important**

Do not use bicapitalization or internal capitalization unless it is part of a brand.

> Examples: YouTube or DreamWorks.

Do not capitalize the spelled-out form of an acronym unless it's a proper noun.

> Example: HyperText Markup Language (HTML).

---

## Body text styling 

#### Bold text 

Use bold for UI elements that appear on the screen, such as buttons, menu items, field labels, and commands.  

> Example: Click **Save** to store your changes.  

Use bold sparingly for emphasis and only when necessary for clarity. Avoid overusing bold for general emphasis in body text.  

#### Keyboard button text

Use the `<kbd>` tags around text that corresponds to a physical button on the keyboard.

<Tabs>
<TabItem value="example" label="Example" default>

Press <kbd>0</kbd>, <kbd>1</kbd>, or <kbd>2</kbd> to select a key scheme and then press <kbd>Enter</kbd>.

</TabItem>

<TabItem value="markdown" label="Markdown">

```
Press <kbd>0</kbd>, <kbd>1</kbd>, or <kbd>2</kbd> to select a key scheme and then press <kbd>Enter</kbd>.
```

</TabItem>
</Tabs>

#### Italic text 

Use italics when introducing a new term for the first time. 

> Example: The term for the cost of processing transaction blocks is _gas_.

#### Slashes {#slashes}

Do not use slashes in place of "and" or "or", such as True / False or True/False. Use True or False, or True | False in code documentation.

---

## Titles and headings 

Use enough words in headings and titles to make it easy to know which link to click on a search results page. One-word titles (for example, Installing) do not provide enough information to determine the contents of a topic.

#### Page titles 

Use **descriptive titles** that include relevant keywords so readers can quickly identify the content. Shorter titles are preferred in the navigation pane. You can set a different navigation title by adding a `sidebar_label` in the document frontmatter.

Readers usually search for information to complete a specific task. Avoid vague titles such as **Get Started**. Get started with what? If there are multiple products or features, the meaning is unclear.

A better option is **Get Started with Sui**, but even this is still too broad. Readers want guidance for a specific task or journey. Instead, use precise titles such as **Create a Sui Full Node** or **Install Sui Tooling**. These tell the reader exactly what they will learn or accomplish.

#### Page headings 

Use heading capitalization style (sentence case). Do not stack headings (place two one after the other without body text in between them).

If something is formatted as inline code in the body, format it the same in the heading.

Do not use a page title as a heading in a different page. This can interfere with search result accuracy. Page titles should be unique and descriptive, while headings can be reused.

> ✅ Correct usage: 
> Page 1: Page title "Sui Gas Profiling" with heading "Environment configuration"
> Page 2: Page title "Sui Indexing" with heading "Environment configuration"

> ❌ Incorrect usage: 
> Page 1: Page title "Sui Gas Profiling" with heading "Environment configuration"
> Page 2: Page title: "Sui Features" with heading "Sui gas profiling"

#### Heading sizes 

- Heading 1: (#) Reserved exclusively for the page title. When the title is specified in the frontmatter, the page is formatted automatically with that title as a Heading 1 element.

- Heading 2: (##) Top-level section headings. Used to introduce new topics on a page.

- Heading 3: (###) Sub-topics for each Heading 2. Used to introduce multiple concepts under a top-level heading.

- Heading 4: (####) Sub-topics for each Heading 3. Used to introduce examples for Heading 3 topics or format sub-sections distinctly. 

- Heading 5: (#####) Sub-topics for each Heading 4. When formatted, looks identical to bolded body text, but slightly larger. Can also be used as an alternative to bolded text to create unique formatting within other elements, such as:

<Tabs>
<TabItem value="example" label="Example" default>

> ##### Heading 5 text.

> **Bold body text.**

> Normal body text.

</TabItem>
<TabItem value="markdown" label="Markdown">

```
> ##### Heading 5 text.

> **Bold body text.**

> Normal body text.
```

</TabItem>
</Tabs>

#### Code elements in section headings

If a word or phrase is formatted in the page content as `inline code`, then it should be formatted the same in a section heading. 

> ##### Section heading: Install `suiup`

> Body content: Install `suiup` using the command: ...

See [inline code](#inline-code) for more information.

---

## Lists {#lists}

Use lists to present items or steps clearly. Introduce a list with a short description ending in a colon (:). Lists should be used in place of sentences that include more than 4 items as a serial comma list. 

All lists should use sentence capitalization unless listing the titles of documentation pages, in which case the title case should be respected..

> Title case example: The Build section includes:
> 
> - Building with Sui  
> - Using the CLI to Start a Network  
> - Creating Smart Contracts  
> - Sui Tutorial  
> - Sui Examples  

> Sentence case example: The Build section includes:
> 
> - For objects, the `tx.object(objectId)` function is used to construct an input that contains an object reference.
> - For pure values, the `tx.pure(type, value)` function is used to construct an input for a non-object input.

#### Numbered lists {#numbered-ordered-lists}

Use when items must be done in order, describe a sequence, or describe a specific number of items.

<Tabs>
<TabItem value="example" label="Example" default>

1. Create a fork of the repo.  
1. Clone your fork of the repo.  
1. Install Sui.  

</TabItem>
<TabItem value="markdown" label="Markdown">

```
1. Create a fork of the repo.
1. Clone your fork of the repo.
1. Install Sui.
```

</TabItem>
</Tabs>

#### Bulleted lists {#bulleted-lists}

Use for related items that do not need order. Use sentence capitalization and consistent punctuation. Add periods only if the item is a full sentence.

<Tabs>
<TabItem value="example" label="Example" default>

Sui Explorer supports the following browsers:

- Firefox version X or later  
- Chrome version X or later  
- Edge version X or later  

</TabItem>
<TabItem value="markdown" label="Markdown">

```
Sui Explorer supports the following browsers:

- Firefox version X or later
- Chrome version X or later
- Edge version X or later
```

</TabItem>
</Tabs>

#### Term lists {#term-list}

Use to define terms or concepts. The term should be bold text, followed by a colon (:) and the term's definition using sentence capitalization: 

> - **Term:** Sentence capitalization used for the term definition. 

<Tabs>
<TabItem value="example" label="Example" default>

- **Term:** A description of the term.  

- **DAG:** A directed acyclic graph (DAG) is a data modeling or structuring tool typically used in data architectures.  

</TabItem>
<TabItem value="markdown" label="Markdown">

```
- **Term:** A description of the term.

- **DAG:** A directed acyclic graph (DAG) is a data modeling or structuring tool typically used in data architectures.
```

</TabItem>
</Tabs>

#### Related links list

At the bottom of a page, you can direct the reader to additional, related content via a related links list. Use the `RelatedLink` component:

External links:

```jsx
<RelatedLink href="/path/to/page" label="Page Title" desc="Description of page." />
```

Internal links:

```jsx
<RelatedLink to="/guides/somepage.mdx" />
```


#### Attribute lists 

Use lists with inline code formatting to list attributes for components such as objects.

<Tabs>
<TabItem value="example" label="Example" default>

An event object in Sui consists of the following attributes:

- `id`: JSON object containing the transaction digest ID and event sequence.
- `packageId`: The object ID of the package that emits the event.
- `transactionModule`: The module that performs the transaction.
- `sender`: The Sui network address that triggered the event.
- `type`: The type of event being emitted.
- `parsedJson`: JSON object describing the event.
- `bcs`: Binary canonical serialization value.
- `timestampMs`: Unix epoch timestamp in milliseconds.

</TabItem>
<TabItem value="markdown" label="Markdown">

```
An event object in Sui consists of the following attributes:

- `id`: JSON object containing the transaction digest ID and event sequence.
- `packageId`: The object ID of the package that emits the event.
- `transactionModule`: The module that performs the transaction.
- `sender`: The Sui network address that triggered the event.
- `type`: The type of event being emitted.
- `parsedJson`: JSON object describing the event.
- `bcs`: Binary canonical serialization value.
- `timestampMs`: Unix epoch timestamp in milliseconds.
```

</TabItem>
</Tabs>

---

## Tables {#tables}

#### Table headings {#table-headings}

Capitalize the first word in the heading. Center align the text. Bold labels in the Header row.

<Tabs>
<TabItem value="example" label="Example" default>

| **Column one** | **Column two** | **Column three** | **Column four** |
| :------------- | :------------: | :--------------: | :-------------- |
| Metric name    |       10       |        X         | Text string.    |

</TabItem>
<TabItem value="markdown" label="Markdown">

```

| **Column one** | **Column two** | **Column three** | **Column four** |

```

</TabItem>
</Tabs>

#### Table alignment {#table-alignment}

Center align labels in the Heading row. Left align strings of text. Center align values and Xs or checkmarks.

<Tabs>
<TabItem value="example" label="Example" default>

| **Column one** | **Column two** | **Column three** | **Column four** |
| :------------- | :------------: | :--------------: | :-------------- |
| Metric name    |       10       |        X         | Text string.    |

</TabItem>
<TabItem value="markdown" label="Markdown">

```

| **Column one** | **Column two** | **Column three** | **Column four** |
| :--- | :---: | :---: | :--- |

```

</TabItem>
</Tabs>

#### Table text {#table-text}

Follow style guidelines for regular body text.

---

## Code {#code}

Words or phrases that refer to functions, object names, CLI tool names, or CLI commands should be formatted as inline code when used in a sentence. 

Use codeblocks for larger sections. Always use actual codeblocks (no images) formatted with the correct syntax highlighting.

#### Inline code {#inline-code}

Use backticks (\`) around inline code. 

Things that should always be formatted as inline code (body and headings) include:

- Object names: `myObject`

- Function names: `HelloWorld`

- File names with extensions: `myPackage.move`

- File extensions: `.jpg`

- CLI tool names: `brew`

- CLI commands when used within a sentence: If using the suggested location, type `export PATH=$PATH:~/sui` and press Enter.

- Variable names: `PATH`

- File paths: `~/.cargo/bin`

#### Console commands 

Console commands must be formatted in three backticks (\`\`\`) and start with `$`.

> Example:
```
$ brew install sui
```

Keep command and response outputs in different code blocks. This ensures commands can be copied and run correctly.

#### Codeblocks {#codeblocks}

Introduce codeblocks with descriptive text, including where the code should be placed within a project:

> Example: Create a new file in the `sources` directory with the name `house_data.move` and populate the file with the following code:

Follow with explanations:

> Example: There are a few details to note in this code:
> 1. The first line declares the module name as `house_data` within the package `satoshi_flip`.
> 1. Seven lines begin with the `use` keyword, which enables this module to use types and functions declared in other modules (in this case, they are all coming from the Sui standard library).
> 1. Two error codes. These codes are used in assertions and unit tests to ensure that the program is running as intended.

Use three backticks (\`\`\`) to initiate, followed by the code's language (Rust, Move, etc) for proper syntax highlighting, and a title indicating the file name.

<Tabs>
<TabItem value="example" label="Example" default>

```move title='house_data.move'
module satoshi_flip::house_data {

  use sui::balance::{Self, Balance};
  use sui::sui::SUI;
  use sui::coin::{Self, Coin};
  use sui::package::{Self};

  // Error codes
  const ECallerNotHouse: u64 = 0;
  const EInsufficientBalance: u64 = 1;

```

</TabItem>
<TabItem value="markdown" label="Markdown">

````
```move title='house_data.move'
module satoshi_flip::house_data {

  use sui::balance::{Self, Balance};
  use sui::sui::SUI;
  use sui::coin::{Self, Coin};
  use sui::package::{Self};

  // Error codes
  const ECallerNotHouse: u64 = 0;
  const EInsufficientBalance: u64 = 1;

```
````

</TabItem>
</Tabs>

---

## Procedures, tasks, and instructions {#procedures-tasks-instructions}

Introduce a procedure with an infinitive verb. Format procedures using a numbered or ordered list.

#### Keyboard keys in procedures {#keyboard-keys-procedures}

When you provide instructions to press keyboard keys, such as Press **Enter** to continue, use uppercase for the key name and format the key name as bold text.

<Tabs>
<TabItem value="example" label="Example" default>

To get the latest version of the Sui Wallet extension:

1. Open Google Chrome.
1. Click **Extensions**, then click **Manage Extensions**.
1. Click **Details** for the Sui Wallet extension, then click **View in Chrome Web Store**.

</TabItem>
<TabItem value="markdown" label="Markdown">

```

To get the latest version of the Sui Wallet extension:

1. Open Google Chrome.
1. Click **Extensions**, then click **Manage Extensions**.
1. Click **Details** for the Sui Wallet extension, then click **View in Chrome Web Store**.

```

</TabItem>
</Tabs>

#### UI elements {#ui-elements}

Format UI elements, such as field labels, button names, and menu commands, in bold text. Always match the exact text or label of the UI element, including capitalization. Do not include special characters, such as ellipses, if included in the element label.

> Example: Click **More Transactions** to open the **Transactions** page.

---

## Links and references

Always use full, relative links when linking to topics on [docs.sui.io].

For the link text, use either:

- The topic title of the target topic, respecting the title case format.

- A portion of the sentence that serves as the link text for the link in a list or "Learn more" sentences. Do not use a URL as the link text.

<Tabs>
<TabItem value="example" label="Example" default>

> To learn more, see [Examples of Sui Smart Contracts](/guides/developer/app-examples.mdx).

</TabItem>
<TabItem value="markdown" label="Markdown">

```markdown
To learn more, see [Examples of Sui Smart Contracts](/guides/developer/app-examples.mdx).

```

</TabItem>
</Tabs>

Use keywords from the target topic title when using inline links.

<Tabs>
<TabItem value="example" label="Example" default>

> Before you install Sui, make sure to install the [prerequisites](/guides/developer/getting-started/sui-install.mdx#prerequisites).

</TabItem>
<TabItem value="markdown" label="Markdown">

```

Before you install Sui, make sure to install the [prerequisites](/guides/developer/getting-started/sui-install.mdx#prerequisites).

```

</TabItem>
</Tabs>

### URLs and web addresses {#urls-web-addresses}

Create a link with descriptive text to a site or URL. Provide the URL only when a reader needs to copy it, such as in example code or configuration files.

### Referring to pages in our docs {#referring}

Refer to pages in the documentation set as "topic"s. A "guide" can comprise many related topics.

> Example: See the Install topic in the Validator guide for more information.

:::info

You can also just refer to a topic by title where it makes sense. See Installing Sui for more information.

:::

---

## Special components

### Collapsible component

Use the `<details><summary>` component to hide long or optional content so it doesn't overwhelm the page. Collapsible sections improve readability while still making supporting information available.  

Use a short, descriptive summary so readers know what's inside. Keep the summary in sentence case.  

Do not nest collapsible components inside one another. Limit collapsible content to material that supplements (not replaces) the visible text.  

#### Use collapsible components for:

- Large code snippets or sample files.  

- Verbose command-line output (for example, logs or stack traces).  

- Extended reference content that readers may not always need.  

#### Do not use collapsible components for:

- Required steps in a procedure. These should always be visible.  

- Short examples or essential commands (collapsing them adds friction). 

- Content that is critical for understanding the main topic.  

<Tabs>
<TabItem value="example" label="Example" default>

<details>
<summary>View full command output</summary>

```
Compiling dependencies...
Finished release [optimized] target(s) in 10.35s
Running `target/release/sui-node`
...
INFO: Sui node is now running
```

</details>

</TabItem>
<TabItem value="markdown" label="Markdown">

````markdown
<details>
<summary>View full command output</summary>

```
Compiling dependencies...
Finished release [optimized] target(s) in 10.35s
Running `target/release/sui-node`
...
INFO: Sui node is now running
```

</details>
````

</TabItem>
</Tabs>

### Alerts {#alerts}

Alerts add emphasis to information. Use Admonitions, a Docusaurus feature, to indicate the alert is a Note, Tip, or Caution. The explanation in the alert must be a complete sentence and use sentence case.

#### Caution {#caution}

Use caution alerts to call out when the following information could cause the developer to lose data, encounter errors, or encounter potentially breaking changes. Always explain the risk clearly.  

<Tabs>
<TabItem value="example" label="Example" default>

:::caution

Backup your configuration files before you delete your network.

:::

</TabItem>
<TabItem value="markdown" label="Markdown">

```

:::caution

Backup your configuration files before you delete your network.

:::

```

</TabItem>
</Tabs>

#### Danger {#danger}

Use danger alerts only for information where the consequences of a mistake are critical, such as permanent data loss, security vulnerabilities, or irreversible actions. Keep the explanation concise and serious in tone.  

<Tabs>
<TabItem value="example" label="Example" default>

:::danger

Deleting this key will permanently remove your access to the account.

:::

</TabItem>
<TabItem value="markdown" label="Markdown">

```

:::danger 

Deleting this key will permanently remove your access to the account.

:::

```

</TabItem>
</Tabs>

#### Info {#info}

Use info alerts to provide important but neutral context that readers should be aware of. It's less about best practices and more about ensuring readers do not miss critical background or conditions.  

<Tabs>
<TabItem value="example" label="Example" default>

:::info

You must install Rust before you can build Sui from source.

:::

</TabItem>
<TabItem value="markdown" label="Markdown">

```

:::info 

You must install Rust before you can build Sui from source.

:::

```

</TabItem>
</Tabs>

#### Note {#note}

While note alerts are a valid admonition, its visual styling is less impactful than other supported admonitions. It is recommended to avoid using note in favor of tip or info.  

<Tabs>
<TabItem value="example" label="Example" default>

:::note

This section applies only if you're using Devnet.

:::

</TabItem>
<TabItem value="markdown" label="Markdown">

```

:::note

This section applies only if you're using Devnet.

:::

```

</TabItem>
</Tabs>

#### Tip {#tip}

Use tip alerts to give the reader advice that might be helpful, such as a best practice or a shortcut.  

<Tabs>
<TabItem value="example" label="Example" default>

:::tip

Change your home directory after installing the IDE.

:::

</TabItem>
<TabItem value="markdown" label="Markdown">

```

:::tip

Navigate into your home directory after installing the IDE.

:::

```

</TabItem>
</Tabs>

---

## Images and graphics {#images-graphics}

Only use images and screenshots to supplement and help explain text. Images do not replace text. Readers should be able to understand the documentation without the images. However, images can help readers understand the text more clearly.

Use [Snagit](https://www.techsmith.com/snagit/) or other tools to capture screenshots.

#### Image format {#image-format}

Use `.png` when possible, otherwise use `.jpg`.

#### Image resolution {#image-resolution}

Images should be at least 400 pixels wide. If an image looks blurry when uploaded, try making a new image in higher resolution.

#### Captions {#captions}

Use alt text to describe what the image shows. Use the caption to explain why the image is meaningful in the context of the page.
See Accessibility considerations for captions.

#### Mermaid for images in Markdown {#mermaid}

You can create flowcharts and similar images directly in Markdown [using Mermaid](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/).

---

## Index pages 

Section index pages must link to subcategory index pages when one exists. This is to ensure users can easily navigate deeper into subsections without relying solely on the sidebar and creates a consistent navigation structure. 

For example, if the docs folder looks like this:

```
/docs/
  guides/
    index.mdx
    setup/
      index.mdx
      install.mdx
```

Then `/docs/guides/index.mdx` must include a link to `/docs/guides/setup/index.mdx` rather than a link to `/docs/guides/setup/install.mdx`.

---

## Accessibility {#accessibility}

Reference works for making content accessible:

- [A11Y Style Guide](https://a11y-style-guide.com/style-guide/)
- [Bitsofcode Accessibility Cheatsheet](https://bitsofco.de/the-accessibility-cheatsheet/)
- [Atlassian Design System - Inclusive writing reference](https://atlassian.design/content/inclusive-writing)
- [MailChimp's writing style guide](https://styleguide.mailchimp.com/writing-for-accessibility/)
- [Microsoft Style Guide Accessibility Terms](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms)
- [Writing for All Abilities](https://learn.microsoft.com/en-us/style-guide/accessibility/writing-all-abilities) (Microsoft Style Guide)

### Formatting {#formatting}

Do not use color or special symbols to add emphasis to text. Screen readers are designed to interpret bold (`<strong>`) and italic (`<em>`) in web pages.

### Images {#images}

Add captions and alt text that describe the image for someone using a screen reader. What are the important details in the image that someone using a screen reader can't see?

Use alt text to describe what the image shows. Use the caption to explain why the image is meaningful in the context of the page.

An image is not a substitute for text; images should only supplement text. Do not rely on an image to convey information not in text form. For example, an image of a table of values does no one any good if the image fails to display for a host of possible reasons.

--- 

## Reference style guides {#reference-style-guides}

- [Write the Docs Style Guide article](https://www.writethedocs.org/guide/writing/style-guides/)
- [GitLab Style Guide](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html) - managed as a community project
- [Digital Ocean Style Guide](https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines)
- [SUSE Style Guide](https://documentation.suse.com/style/current/#sec-techwriting)
- [Microsoft Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/)
- [Google Developer Style Guide](https://developers.google.com/style)
- [CDN Language and Style Reference](http://cdn.static-economist.com/sites/default/files/pdfs/style_guide_12.pdf)
